Overview
| Oracle® OLAP Analytic Workspace Java API Reference 10g Release 2 (10.2) B14351-02

# Steps in Creating an Analytic Workspace

The Oracle OLAP Application Developer's Guide describes the process of designing and creating an analytic workspace using Analytic Workspace Manager. The `BuildAWExample.java` program creates a similar analytic workspace by using the Analytic Workspace Java API.

The `BuildAWExample` program creates objects that implement the following tasks described in the Oracle OLAP Application Developer's Guide.

- Define the connection to the database.
- Design the logical multidimensional model for the analytic workspace.
- Map the logical objects to relational data sources.
- Load the data.

The data sources are columns in the relational tables of the Global Schema for Documentation sample schema. This document outlines the sequence in which the program creates the Analytic Workspace Java API objects. The code examples are from the program. Each line of code is preceded by the number of the line in the program.

The program accomplishes other tasks that are not included in this outline, such as creating a measure folder, writing an XML representation of the objects to a file, and creating a log file that records the creation of the objects.

## Defining the Connection to the Database

To define a connection to the Oracle Database, the program declares an `AWConnection` as a class variable and instantiates it using values passed in as command line arguments.

`64 public static AWConnection awConnection;`
`123 awConnection = new AWConnection(user, password, connection);`

For a description of the `user`, `password`, `connection` objects, see the explanation beginning on line 1136 of the program or the description of the constructor of the AWConnection class.

## Creating Objects That Implement the Multidimensional Model

The `BuildAWExample` program implements a multidimensional model that associates dimensions, levels, hierarchies, attributes, cubes, and measures with an analytic workspace. The program first creates an `AW` object to represent the analytic workspace. It then creates `Dimension` objects and the `Attribute`, `Level`, and `Hierarchy` objects associated with each `Dimension`. Next, it creates `Cube` and `Measure` objects.

### Creating the AW Object

The following lines from the program create the `AW` object and specify a name for it.

`131 String awname="GLOBALAW";`
`137 AW globalAW = new AW();`
`138 globalAW.setName(awName);`

### Creating Dimension and Related Objects

The program creates a `Dimension` object for each of the logical dimensions of the analytic workspace. This outline includes only the creation of a `Dimension` for a dimension that has time values as its members. Because a time dimension has attributes that other dimensions do not have, line 163 specifies that the `Dimension` is a time dimension.

`144 Dimension timeDim = globalAW.createDimension();`
`145 timeDim.setName("TIME_AW");`
`148 timeDim.setIsTime(true);`

The members of the dimensions of the analytic workspace are organized into level-based hierarchies. For each `Dimension`, the program creates `Attribute`, `Level`, and `Hierarchy` objects.

The program has separate methods that creates those objects for each `Dimension`. The following code is in the `createTimeDim` method that begins on line 424. Line 428 indicates that the primary key of the dimension table contains the lowest-level dimension members.

`426 timeDim.setUseNativeKey(true);`

The following lines create one of the `Attribute` objects associated with the `Dimension`. Creation of `Attribute` objects for the other attributes of the dimension is not shown.

`436 Attribute timeTimeSpanAttr = timeDim.createAttribute();`
`437 timeTimeSpanAttr.setName("Time_Span");`
`438 timeTimeSpanAttr.setClassification("TIME_SPAN");`

The members of the dimension are organized into a hierarchical relationship that is defined by levels. The levels are represented by `Level` objects and the hierarchy is represented by a `Hiearchy` object.

The following lines create a `Level` for the lowest-level members of dimension, which are month values.

`443 Level monthLevel = timeDim.createLevel();`
`444 monthLevel.setName("MONTH");`

An `AttributeProjection` associates an `Attribute` with a `Level`. In the `BuildAWExample` program, the `setupAttributeProjection` method creates the `AttributeProjection` objects. The following lines are from that method, but have the values passed to the method for creating an `AttributeProjection` for the time span attribute for the month level.

`951 AttributeProjection month_ap = monthLevel.createAttributeProjection();`
`952 month_ap.setName("Time Span");`
`953 month_ap.setAttribute(timeTimeSpanAttr);`

The next line creates a `Hierarchy` object and associates it with the `Dimension`.

`508 Hierarchy calendarHier = timeDim.createHierarchy();`
`509 calendarHier.setName("CALENDAR_AW");`

### Creating Cube, Measure, and Related Objects

The program creates a `Cube` object for each set of `Measure` objects that is dimensioned by the same set of `Dimension` objects. The following lines illustrate the creation of a `Cube` that associates a measure with its dimensions. The data in the measure is the quantity of product units sold. The measure is dimensioned by dimensions for time, customers, products, and sales channels.

The following lines create a `Cube` and specify a name for it.

`199 Cube unitsCube = globalAW.createCube();`
`200 unitsCube.setName("UNITS_CUBE_AW");`

A `CubeDimRef` associates a `Dimension` with a `Cube`. The program has an `associateCubeDimensions` method, which begins on line 1054, that creates a `CubeDimRef` for each dimension that dimensions the measures associated with the `Cube`. The following lines from that method have values that create a `CubeDimRef` for the time dimension.

`1058 CubeDimRef unitsCube_cdr = unitsCube.createCubeDimRef();`
`1060 unitsCube_timeDimCubeDimRef.setDimension(timeDim);`

The program creates `Measure` objects and associate them with a `Cube`. The following lines create a `Measure` for the units `Cube`, and specify a name and a data type for the `Measure`.

`215 Measure units = unitsCube.createMeasure();`
`217 units.setName("UNITS_AW");`
`220 units.setDataType("NUMBER");`

## Mapping the Logical Objects to Relational Data Sources

The Analytic Workspace Java API uses `MappingGroup` classes to map relational data sources to their target `AWObject` objects. For a diagram of the class hierarchy and associations of `MappingGroup`, see MappingGroup Class Associations.

### Mapping Level Objects

The `BuildAWExample` program has a `createLevelMap` method that maps the `Level` and `AttributeProjection` objects to columns in the relational tables of the Global Schema for Documentation. The following lines are from that method, but have the values passed to the method for creating the objects that map the month level and time span attribute to relational source columns.

The `DimensionMapGroup` owns the `DimensionKeySourceExpression` and `AttributeSourceExpression` objects. Each of those `ExternalSourceExpression` objects has a `SourceColumn` that specifies the column to which the `Level` or `AttributeProjection` is mapped.

`973 DimensionMapGroup month_dmg = monthLevel.createSourceDimensionMapGroup();`
`974 DimensionKeySourceExpression month_key = month_dmg.CreateKeyMap();`

`978 SourceColumn month_keycol = month_key.CreateSourceColumn();`
`979 month_keycol.setColumn("GLOBAL.TIME_DIM.MONTH_ID");`

`988 AttributeSourceExpression monthTS_attrMap = month_dmg.CreateAttributeMap();`
`989 monthTS_attrMap.setTargetObject(timeTimeSpanAttr);`
`990 SourceColumn monthTS_attrCol = monthTS_attrMap.CreateSourceColumn();`
`991 monthTS_attrCol.setColumn("GLOBAL.TIME_DIM.MONTH_TIMESPAN");`

### Mapping Hierarchy Objects

The `createHierarchyMap` method, which begins on line 999, associates `Level` objects with a `Hierarchy`, specifies a source column for each `Level`, and specifies the parent `Level` for each `Level` except the highest one. The following lines are from that method, but have the values passed to the method for creating the objects that associate the time dimension levels with the `calendarHier` `Hierarchy`.

The method creates a `HierarchyLevelAssociation` for each `Level` and then creates a set of mapping objects for each `HierarchyLevelAssociation`. The following lines use values that create the objects for the month `Level`.

`1005 HierarchyLevelAssociation month_hla =calendarHier.createHierarchyLevelAssociation();`
`1006 month_hla.setLevel(monthLevel);`

`1008 DimensionMapGroup month_hla_dmg = month_hla.createSourceDimensionMapGroup();`
`1009 DimensionKeySourceExpression month_hla_dmg_dkse = month_hla_dmg.CreateKeyMap();`
`1010 SourceColumn month_levColumn = month_hla_dmg_dkse.CreateSourceColumn();`
`1011 month_levColumn.setColumn("GLOBAL.TIME_DIM.MONTH_ID");`

For each `Level` except the highest one, the `createHierarchyMap` method creates a `HierarchicalParentSourceExpression` that associates the `Level` with its parent and that has a `SourceColumn` that maps a relational column to the parent. The following lines create a parent map for the month `Level`.

`1018 HierarchicalParentSourceExpression month_hla_dmg_hpse = month_hla_dmg.CreateParentMap();`
`1019 SourceColumn month_hla_dmg_hpsesc = month_hla_dmg_hpse.CreateSourceColumn();`
`1020 month_hla_dmg_hpsesc.setColumn("GLOBAL.TIME_DIM.QUARTER_ID");`

### Mapping Cube Objects

The `createCubeMap` method, which begins on line 1068, creates a `CubeMapGroup` for the `Cube`. The method creates objects that map the lowest levels of the dimensions to their source columns and that map the measures to their source columns. It associates those objects with the `CubeMapGroup`.

The following lines are from the `createCubeMap` method but have the values passed to the method for creating the objects for the units `Cube`. The lines create a `CubeMapGroup`, and then create a `CubeDimensionSourceExpression` for the lowest level of the time dimension and associate a source column with it.

`1071 CubeMapGroup units_cmg = units.createSourceCubeMapGroup();`
`1076 CubeDimensionSourceExpression item_cdse = units_cmg.CreateKeyMap();`
`1077 month__cdse.addLevel(monthLevel);`
`1085 SourceColumn month_keycol = month__cdse.CreateSourceColumn();`
`1086 month_keycol.setColumn("GLOBAL.UNITS_HISTORY_FACT.MONTH_ID");`

The next lines specify that Oracle OLAP does not automatically calculate the aggregated values for the measure. They map the measure to a source column for the `Cube` by creating `MeasureSourceExpression` and `SourceColumn` objects and specifying the column.

`1093 units.setAutoSolve("NO_AUTO_SOLVE");`
`1095 MeasureSourceExpression units_measMap = units_cmg.CreateAttributeMap();`
`1096 units_measMap.setTargetObject(units);`
`1097 SourceColumn units_meascol = _measMap.CreateSourceColumn();`
`1098 units_meascol.setColumn("GLOBAL.UNITS_HISTORY_FACT.UNITS");`

### Loading the Data

After creating the objects that represent the logical model of the analytic workspace and mapping the objects to the data source columns, the program uses action methods of the `AW` object to create the structures in the analytic workspace and to commit them to the relational database. The next two lines call those methods.

`312 globalAW.Create(awConnection);`
`313 globalAW.Commit(awConnection);`

The program then uses classes from the `AWAction` package to build the analytic workspace and populate it with data. In the program, the method `xml_build_global_aw`, which begins on line 397, accomplishes those tasks. The following lines are from that method. The `curInteraction` object is a class variable declared on line 65.

`400 curInteraction = new Interaction();`
`403 curInteraction.setConnection(awConnection);`
`406 BuildDatabase myBuild =`
`407 (BuildDatabase)curInteraction.createAction("BUILDDATABASE");`
`410 myBuild.setAWName(awName);`
`416 myBuild.Execute();`

Finally, the program closes the connection to the database.

`391 awConnection.close();`

Copyright © 2003, 2005, Oracle. All rights reserved.